Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Port Functions / Manipulating View Port Object Properties

GXSetViewPortTags

You can use the GXSetViewPortTags function to add, remove, or replace tag objects associated with a view port object.

void GXSetViewPortTags(gxViewPort target, long tagType, 
                        long index, long oldCount, 
                        long newCount, const gxTag items[]);

target

A reference to the view port whose tag list you want to alter.

tagType

The type of tag objects to replace. A value of 0 indicates that you want to replace tags of all types.

index

The (1-based) index of the first tag reference (to a tag object of the appropriate type) to replace.

oldCount

The number of tag references to replace. A value of 0 specifies that you want to insert tag references before the tag reference indicated by the index parameter, rather than replace tag references. A value of -1 (the gxSelectToEnd constant) specifies that all tag references of the requested type, starting with the tag reference indicated by the index parameter, should be replaced.

newCount

The number of tag references to insert. A value of 0 specifies that there are no tag references to insert; the existing tag references that match the criteria you specify are removed from the source shape's tag list and disposed of.

items

An array of tag references to insert in the tag list.

DESCRIPTION

The GXSetViewPortTags function allows you add tag references to a view port object's tag list, to remove tag references from the list, or to replace tag references in the list with new tag references. In any of these three cases, the target parameter specifies the view port object to be modified, the newCount parameter specifies the number of tag references to add, and the items parameter provides the new tag references.

• To add tag references, set the oldCount parameter to 0. Use the tagType and the index parameters to specify where to add the new tag references. (For example, if you specify nil for the tagType parameter and 1 for the index parameter, this function inserts the new tag references before the current tag references. If you specify a value other than nil for the tagType parameter and a value of 2 for the index parameter, the function inserts the new tag references before the second tag reference with a tag type matching the tagType parameter.)
• To remove tag references, set the newCount parameter to 0 and the items parameter to nil. You can use the index and the oldCount parameters to specify which tag references (of the specified type) should be removed. The index parameter indicates the first tag reference (of the specified type) to remove and the oldCount parameter indicates how many tag references (of the specified type) to remove.
• To replace tag references, use the tagType, index, and oldCount parameters to indicate which tag references to replace, and use the newCount and items parameters to specify the new tag references to add. If newCount is greater than oldCount, the extra tag references are placed immediately adjacent to the last tag reference replaced.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
invalid_viewPort_reference
tag_is_nil
parameter_is_nil	(debugging version)
inconsistent_parameters	(debugging version)
parameter_out_of_range	(debugging version)
index_is_less_than_zero	(debugging version)
cannot_dispose_locked_tag	(debugging version)
Warnings
index_out_of_range
count_out_of_range
Notices (debugging version)
tag_already_set

SEE ALSO

Tag objects are discussed in the chapter "Tag Objects" in this book.

To examine the set of tag references associated with a view port, use the GXGetViewPortTags function, described in the previous section.